home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / unarced / languages / c-manual / windows / windows.doc < prev    next >
Text File  |  1995-03-17  |  37KB  |  1,095 lines
  1. 2    WINDOWS
  2.  
  3. 2.1  INTRODUCTION
  4.  
  5. Windows are rectangular boxes which can be as big as the screen
  6. or only 1 pixel wide. They can be resized, moved around on the
  7. screen, put in front or behind other windows and so on. All
  8. this is taken care of Intuition, and your program does not even
  9. need to know about it if you do not want.
  10.  
  11. The aim with Windows is to make the communication between the
  12. user and the computer as easy as possible. Windows gives the
  13. user a structured display which is easy to understand. It also
  14. allows the user to interact with the programs through graphics
  15. symbols (gadgets) which can be connected to the windows. (See
  16. chapter 4 GADGETS for more information about gadgets.)
  17.  
  18. Windows are working close together with screens, since the
  19. screen's resolution etc affects the way the windows are drawn.
  20. Moving a screen will also result in moving all the windows
  21. connected to that screen.
  22.  
  23.  
  24.  
  25. 2.2  SPECIAL WINDOWS
  26.  
  27. The normal windows are rectangular boxes with a border around.
  28. However, there exist some special types of windows:
  29.  
  30.  
  31.  
  32. 2.2.1  BACKDROP WINDOWS
  33.  
  34. Backdrop Windows will always be behind any other windows. This
  35. allows you to have a window in the bottom of the display, and
  36. it will stay there, even if the user is using the "depth-
  37. arrange gadgets".
  38.  
  39. Backdrop Windows differ from other windows since:
  40.  
  41. - It will always open behind all other windows, including other
  42.   already opened Backdrop Windows.
  43.  
  44. - The "close-window gadget" is the only System Gadget you can
  45.   attach to a Backdrop Window. (You can of course attach your
  46.   own gadgets as usual.)
  47.  
  48. - It will always be behind of any other windows. 
  49.  
  50. The Backdrop Window is very handy when you want to have a
  51. bottom drawing (for example your main display), with some tools
  52. etc on top of the bottom window. This allows the user to move
  53. around your tools as he/she wants without needing to worry
  54. about hiding the windows behind the main display.
  55.  
  56. Drawing into a Backdrop Window instead of the screen itself is
  57. very common since you can then not draw anything at the wrong
  58. moment. If a menu (See chapter 5 MENUS for more information) is
  59. displayed, the drawing routines will wait automatically, and
  60. will therefore not destroy the menu, as it would have happened
  61. if you were drawing directly into the screen.
  62.  
  63.  
  64.  
  65. 2.2.2  BORDERLESS WINDOWS
  66.  
  67. Borderless windows are as normal windows except that they
  68. (surprise, surprise) do not have any borders. It is very common
  69. to combine a Borderless window with a Backdrop window, to cover
  70. a screen.
  71.  
  72. It can be confusing for the user if a Borderless window does
  73. not cover the entire display, since he/she will not be able to
  74. see where the window's edges are. It is therefore normally
  75. best to make a Borderless window as big as the screen.
  76.  
  77.  
  78.  
  79. 2.2.3  GIMMEZEROZERO WINDOWS
  80.  
  81. A Gimmezerozero Window is as a normal window, except that it
  82. consist of two drawing areas: one Outer and one Inner window.
  83. The Outer window is used for displaying the borders, system
  84. gadgets etc, while the Inner window is only used by yourself.
  85.  
  86. If you are drawing into a normal window you need to start some
  87. pixels down/out (11, 1), so you don not draw into the borders
  88. etc. However, if you are drawing into a Gimmezerozero Window
  89. you do not need to make any adjustments. The top left corner of
  90. your inner window is always at the position (0,0).
  91.  
  92. Gimmezerozero Windows are therefore very handy if you want to
  93. make a lot of drawings, without wanting to worry about the
  94. borders. The disadvantages is that it takes more memory and
  95. processing time than a normal window.
  96.  
  97.  
  98.  
  99. 2.2.4  SUPERBITMAP WINDOWS
  100.  
  101. If you are using a SuperBitMap Window you allocate display
  102. memory yourself for the window instead of letting Intuition
  103. take care of it. The advantage is that you can define a larger
  104. drawing area then the size of the window. You can then scroll
  105. the drawing area inside the window. A good example of this are
  106. the demo programs that followed with you Workbench disk when
  107. you bought your computer.
  108.  
  109. It normally best to combine a SuperBitMap Window together with
  110. a Gimmezerozero Window. The borders etc will then NOT be drawn
  111. into your SuperBitMap, and will instead be drawn in the Outer
  112. window. This allows you to make whatever you want with the
  113. inner window without destroying any borders etc.
  114.  
  115.  
  116.  
  117. 2.3  SYSTEM GADGETS
  118.  
  119. The System Gadgets enables the user to move the window, resize
  120. it, push it behind other windows etc, without your program even
  121. knowing about it. The System Gadgets are controlled by
  122. Intuition, and are always looking the same. The only thing you
  123. need to do is to tell Intuition which gadgets you want, and the
  124. rest is done for you.
  125.  
  126. The five System Gadgets are placed like this:
  127.  
  128.  1       2       3  4
  129. [*][***********][*][*]
  130. |                    |
  131. |       WINDOW       |
  132. |                    |
  133. |                    |
  134. |__________________[*]
  135.                     5
  136.  
  137. 1  Close Gadget. Press this to close the window. (This is the
  138.    only System Gadget which your program have to respond to.
  139.    Your program will be told that the user has clicked on the
  140.    Close Gadget, but you need to close the window yourself by
  141.    calling the function CloseWindow().)
  142.  
  143. 2  Drag Gadget. Pressing the left mouse button somewhere on it
  144.    and move the mouse while the button is still pressed, will
  145.    move the window. If your window has a title it will be
  146.    displayed over the Drag Gadget, but will not interfere with
  147.    it.
  148.  
  149. 3  Depth-Arrangement Gadget BACK. Clicking on this gadget will
  150.    push the window behind all other windows.
  151.  
  152. 4  Depth-Arrangement Gadget UP. Clicking on this gadget will
  153.    put the window in front of all other windows.
  154.  
  155. 5  Sizing Gadget. Pressing the left mouse button somewhere on
  156.    it and move the mouse while the button is still pressed,
  157.    will change the size of the window.
  158.  
  159.  
  160.  
  161. 2.4  REDRAWING THE WINDOW DISPLAY
  162.  
  163. Since windows can be dragged around the screen it is very
  164. common that they sometimes overlap each other. If the user is
  165. then moving away the top window, the bottom window has to be
  166. refreshed.
  167.  
  168. There exist two methods of redrawing the window:
  169. - Simple Refresh. Intuition will only tell you that you need
  170.   to refresh it, and your program has to redraw everything
  171.   itself.
  172. - Smart Refresh. Intuition saves the oscured pieces, and
  173.   replaces them automatically. Needs more memory than Simple
  174.   Refresh, but redraws the display much faster.
  175.  
  176. If you have a SuperBitMap Window, you have allocated the
  177. display memory yourself, and your window will therefore not be
  178. destroyed by other windows.
  179.  
  180. If you change the size of a Simple Refresh Window, or it is
  181. reveled after having been overlapped, Intuition will tell you
  182. that you need to refresh the window. A Smart Refresh Window
  183. will only ask you to redraw its display if you enlarged it.
  184.  
  185. The IDCMP message "REFRESHWINDOW" tells you that the window
  186. needs to be refreshed. (See chapter 8 IDCMP for more about
  187. IDCMP flags.)
  188.  
  189. IMPORTANT! If your program receive a REFRESHWINDOW message you
  190. must call the functions BeginRefresh() - EndRefresh():
  191.  
  192. - BeginRefresh() will make the redrawing as fast as possible.
  193.   Only the destroyed pieces of the window will be refreshed.
  194.  
  195. - EndRefresh() tells Intuition that you are finished with the
  196.   redrawing.
  197.  
  198. If you receive a REFRESHWINDOW message and you do not want to
  199. redraw the display, you should still call the two functions.
  200. This will clear up the system and reorganize the Layer Library.
  201.  
  202.  
  203.  
  204. 2.5  INITIALIZE A WINDOW
  205.  
  206. Before you can open a window you need to initialize a NewWindow
  207. structure which look like this:
  208.  
  209. struct NewWindow
  210. {
  211.   SHORT LeftEdge, TopEdge;
  212.   SHORT Width, Height;
  213.   UBYTE DetailPen, BlockPen;
  214.   ULONG IDCMPFlags;
  215.   ULONG Flags;
  216.   struct Gadget *FirstGadget;
  217.   struct Image *CheckMark;
  218.   UBYTE *Title;
  219.   struct Screen *Screen;
  220.   struct BitMap *BitMap;
  221.   SHORT MinWidth, MinHeight;
  222.   SHORT MaxWidth, MaxHeight;
  223.   USHORT Type;
  224. };
  225.  
  226. LeftEdge:     Initial x position of the window.
  227.  
  228. TopEdge:      Initial y position of the window.
  229.  
  230. Width:        Initial width of the window. If the window is
  231.               connected to a high-resolution screen, it can be
  232.               anything between 1 and 640. Otherwise (low-
  233.               resolution screen) it can be between 1 and 320.
  234.  
  235. Height:       Initial height of the window. Can be anything
  236.               between 1 and the height of the screen.
  237.  
  238. DetailPen:    The colour register used to draw the text with.
  239.  
  240. BlockPen:     The colour register used for block fills etc.
  241.  
  242. IDCMPFlags:   See chapter 8 IDCMP for a list and explanations
  243.               of the flags.
  244.               
  245. Flags:        If you want any System Gadgets, a special window
  246.               (Borderless, Backdrop etc), you set the desired
  247.               flags:
  248.  
  249.               System Gadgets:
  250.  
  251.               WINDOWCLOSE
  252.                 This will put the Close Gadget into the top
  253.                 left corner of your window. (Remember that this
  254.                 is the only System Gadget your program need to
  255.                 response to. Intuition will simply inform you
  256.                 that the user wants to close the window, but
  257.                 you need to close the window yourself by
  258.                 calling the CloseWindow() function.
  259.  
  260.               WINDOWDRAG
  261.                 This makes the whole title bar into a gadget,
  262.                 which allows the user to move around the
  263.                 Window.
  264.  
  265.               WINDOWDEPTH
  266.                 If you want that the user should be able to
  267.                 push the window in front, or behind all other
  268.                 windows you set this flag. The gadgets (to the
  269.                 back and to the front) will be placed in the
  270.                 top right corner of the window.
  271.  
  272.               WINDOWSIZING
  273.                 This enables the user to resize the window as
  274.                 desired. (You can specify the maximum and
  275.                 minimum size of the window by setting the
  276.                 MinWidth/MinHeight/MaxWidth/MaxHeight
  277.                 variables)
  278.                 
  279.                 The Size Gadget will be placed in the right
  280.                 border as default (SIZEBRIGHT), but can also be
  281.                 put in the bottom border (set the flag 
  282.                 SIZEBOTTOM) if you want the window display to
  283.                 be as wide as possible.
  284.  
  285.  
  286.               Special Windows:
  287.               
  288.               BACKDROP
  289.                 Set this flag if you want a Backdrop Window.
  290.  
  291.               BORDERLESS
  292.                 Set this flag if you want a Borderless Window.
  293.  
  294.               GIMMEZEROZERO
  295.                 Set this flag if you want a Gimmezerozero
  296.                 Window.
  297.  
  298.               SUPER_BITMAP
  299.                 Set this flag if you want a SuperBitMap Window.
  300.                 (If you are going to use your own allocated
  301.                 BitMap you also need to set the BitMap variable
  302.                 to point to your BitMap structure. Explained
  303.                 later in this chapter.)
  304.  
  305.  
  306.               Refreshing Flags. If you do not use a SuperBitMap
  307.               Window you need to set one of these two flags:
  308.  
  309.               SIMPLE_REFRESH
  310.                 Your program must redraw the display itself.
  311.  
  312.               SMART_REFRESH
  313.                 Intuition will automatically redraw the display
  314.                 if necessary. It is only when the user make the
  315.                 window bigger you need to redraw the display
  316.                 yourself.
  317.  
  318.  
  319.               Other flags:
  320.  
  321.               REPORTMOUSE
  322.                 Set this flag if you want to receive the pointer
  323.                 movements as x,y coordinates. (See chapter 8
  324.                 IDCMP for more information.)
  325.  
  326.               NOCAREREFRESH
  327.                 Set this flag if you do not want to receive any
  328.                 messages telling you to redraw your window.
  329.  
  330.               RMBTRAP
  331.                 Set this flag if you do not want that the user
  332.                 to be able to access any menus while this
  333.                 window is active. (If you want that the right
  334.                 mouse button on the mouse should be used for
  335.                 something else than menu operations, you
  336.                 should set this flag. See chapter 8 IDCMP for
  337.                 more information.)
  338.  
  339.               ACTIVATE
  340.                 Set this flag if you want the window to become
  341.                 active when it is opened. The user can of
  342.                 course activate some other window later if
  343.                 he/she wants. (Clicking inside a window will
  344.                 activate it, and all input will go to the new
  345.                 active window. All other widows will become
  346.                 inactive, and their title bars will become
  347.                 "ghosted".)
  348.  
  349. FirstGadget:  A pointer to the first Gadget in your list, or
  350.               NULL if you do not have any own gadgets connected
  351.               to the window. (See chapter 4 GADGETS for more
  352.               information about gadgets.)
  353.  
  354. CheckMark:    A pointer to an Image structure (See chapter 3
  355.               GRAPHICS for more information about Image
  356.               structures) which will be used for selected menus
  357.               items. (See chapter 7 MENUS for more information
  358.               about menus.) If no pointer is given (NULL)
  359.               Intuition will use the default checkmark.
  360.  
  361. Title:        A pointer to a NULL-terminated string that will
  362.               be used as window's title. The string will appear
  363.               on the title bar, at the top of the window.
  364.  
  365. Screen:       A pointer to your Custom Screen, or NULL if the
  366.               window should be connected to the Workbench
  367.               Screen. (If the window is connected to the
  368.               Workbench Screen set the Type variable to
  369.               WBENCHSCREEN, otherwise set it to CUSTOMSCREEN.)
  370.  
  371. BitMap:       If you are going to use a SuperBitMap Window,
  372.               then you need to give Intuition a pointer to your
  373.               own initialized BitMap structure, otherwise write
  374.               NULL. (Remember to set the Flag SUPER_BITMAP, and
  375.               you should probably also make the window into a
  376.               Gimmezerozero Window.)
  377.  
  378. If you have asked for the System Gadget WINDOWSIZING you need
  379. to decide the minimum/maximum size of your window, otherwise
  380. you can ignore these variables. If any variable is set to zero
  381. the initial size (Width/Height) will be used as max/min size:
  382.  
  383. MinWidth:     Minimum width of the window.
  384.  
  385. MinHeight:    Minimum height of the window.
  386.  
  387. MaxWidth:     Maximum width of the window.
  388.  
  389. MaxHeight:    Maximum height of the window.
  390.  
  391. Type:         If your window should be connected to the
  392.               Workbench Screen you write WBENCHSCREEN,
  393.               otherwise you write CUSTOMSCREEN. (If you set
  394.               the CUSTOMSCREEN flag you need to give the Screen
  395.               variable a pointer to your already opened Custom
  396.               Screen.
  397.               
  398.               It is common that you declare and initialize the
  399.               NewWindow structure with your requirements,
  400.               except that you ignore (NULL) the Screen pointer.
  401.               You then open your Custom Screen, and first now
  402.               initialize the Screen pointer with the pointer
  403.               returned from the OpenScreen() function. (See
  404.               Example 2 for more information.)
  405.  
  406.  
  407.  
  408. 2.6  OPEN A WINDOW
  409.  
  410. The procedure to open windows is very similar to open Custom
  411. Screens. The idea is that you declare a NewWindow structure
  412. (similar to NewScreen) and initialize it with the requirements.
  413. You then simply call the function OpenWindow() (similar to
  414. OpenScreen()) with your NewWindow structure, and the function
  415. returns a pointer to your Window structure. You will now not
  416. need the NewWindow structure any more (if you do not want to
  417. open more windows using the same structure of course).
  418.  
  419. This is how you call the OpenWindow() function:
  420.  
  421. my_window = OpenWindow( &my_new_window );
  422.  
  423. my_window has been declared as:
  424.   struct Window *my_window;
  425.   
  426. my_new_window has been declared as:
  427.   struct NewWindow *my_new_window;
  428.   and has been initialized with your requirements.
  429.  
  430. OpenWindow() will return a pointer to your Window structure. If
  431. it could not open the Window (for example, not enough memory)
  432. it will return NULL. Remember therefore to check what
  433. OpenWindow() returned:
  434.  
  435. if( my_window == NULL )
  436. {
  437.   /* PANIC! Could not open the window */
  438. }
  439.  
  440.  
  441.  
  442. 2.7  WINDOW STRUCTURE
  443.  
  444. Once you have opened the window you will receive a pointer
  445. (my_window) to a Window structure:
  446.  
  447. struct Window
  448. {
  449.     struct Window *NextWindow;  /* Pointer to next window. */
  450.     SHORT LeftEdge, TopEdge;    /* Position of the window. */
  451.     SHORT Width, Height;        /* Size of the window. */
  452.     SHORT MouseY, MouseX;       /* Position of the pointer */
  453.                                 /* relative to the top left */
  454.                                 /* corner of the window. */
  455.     SHORT MinWidth, MinHeight;  /* Minimum/Maximum size of */
  456.     USHORT MaxWidth, MaxHeight; /* the window. */
  457.  
  458.     ULONG Flags;                /* The window's flags. */
  459.  
  460.     struct Menu *MenuStrip;     /* Pointer to the window's */
  461.                                 /* first menu. */
  462.  
  463.     UBYTE *Title;               /* The window's title. */
  464.  
  465.     struct Requester *FirstRequest;
  466.     struct Requester *DMRequest;
  467.     SHORT ReqCount;
  468.  
  469.     struct Screen *WScreen;     /* A pointer to the Screen */
  470.                                 /* which the window is */
  471.                                 /* connected to. */
  472.     struct RastPort *RPort;     /* The window's RastPort. */
  473.  
  474.     BYTE BorderLeft, BorderTop, BorderRight, BorderBottom;
  475.  
  476.     struct RastPort *BorderRPort; /* If your window is a */
  477.                                   /* Gimmezerozero this a */
  478.                                   /* pointer the the Outer */
  479.                                   /* window's RastPort. */
  480.  
  481.     struct Gadget *FirstGadget;
  482.     struct Window *Parent, *Descendant;
  483.  
  484.     USHORT *Pointer;            /* Data for the Pointer. */
  485.     BYTE PtrHeight;             /* Height of the pointer. */
  486.     BYTE PtrWidth;              /* Width of the pointer. */
  487.     BYTE XOffset, YOffset;      /* "Hot Spot" of the pointer. */
  488.  
  489.     ULONG IDCMPFlags;           /* The IDCMP flags. */
  490.  
  491.     struct MsgPort *UserPort, *WindowPort;
  492.     struct IntuiMessage *MessageKey;
  493.  
  494.     UBYTE DetailPen, BlockPen;
  495.     struct Image *CheckMark;
  496.  
  497.     UBYTE *ScreenTitle;         /* The title of the screen */
  498.                                 /* which the window is */
  499.                                 /* connected to. */
  500.  
  501.     /* These are only used if you have opened a */
  502.     /* Gimmezerozero window: */
  503.     SHORT GZZMouseX; /* Position of the mouse relative to */
  504.     SHORT GZZMouseY; /* the inner window. */
  505.     SHORT GZZWidth;  /* Size of the inner window. */
  506.     SHORT GZZHeight;
  507.  
  508.     UBYTE *ExtData;
  509.     BYTE *UserData;
  510.     struct Layer *WLayer;
  511.     struct TextFont *IFont;
  512. };
  513.  
  514.  
  515.  
  516. 2.8  OPEN A SUPERBITMAP WINDOW
  517.  
  518. The difference in opening a normal window and a SuperBitMap
  519. window is that Intuition will allocate display memory for the
  520. normal window automatically, while a SuperBitMap window has to
  521. allocate the memory itself. However, it is actually not so
  522. hard as it may seem. You just need to follow these steps:
  523.  
  524. 1. Declare and initialize a NewWindow structure with your
  525.    requirements.
  526.    (Set the Flags = SUPER_BITMAP, and BitMap=NULL)
  527.  
  528.    struct NewWindow my_new_window={ .... };
  529.  
  530.  
  531. 2. Declare a BitMap structure:
  532.  
  533.    struct BitMap my_bitmap;
  534.  
  535.  
  536. 3. Initialize your own BitMap by calling the function:
  537.  
  538.    InitBitMap( &my_bitmap, Depth, Width, Height );
  539.      &my_bitmap: A pointer to the my_bitmap structure.
  540.      Depth:      Number of bitplanes to use.
  541.      Width:      The width of the BitMap.
  542.      Height:     The height of the BitMap.
  543.  
  544.  
  545. 4. Allocate display memory for the BitMap:
  546.  
  547.    for( loop=0; loop < Depth; loop++)
  548.      if( (my_bitmap.Planes[loop] = AllocRaster( Width,
  549.        Height )) == NULL )
  550.      {
  551.        /* PANIC! Not enough memory */
  552.      }
  553.  
  554.  
  555. 5. After you have allocated the display memory, it normally
  556.    best to clear the Bitplanes:
  557.  
  558.    for( loop=0; loop < Depth; loop++)
  559.      BltClear(my_bitmap.Planes[loop], RASSIZE(Width, Height), 0);
  560.  
  561.  
  562. 6. Make sure the NewWindow's BitMap pointer is pointing to your
  563.  
  564.    BitMap structure:
  565.      my_new_window.BitMap=&my_bitmap;
  566.  
  567.  
  568. 7. At last you can open the window:
  569.  
  570.    my_window = OpenWindow( &my_new_window );
  571.  
  572.  
  573. 8. Do not forget to close the window, AND deallocate the
  574.    display memory:
  575.  
  576.    CloseWindow( my_window );
  577.  
  578.    for( loop=0; loop < Depth; loop++)
  579.     if( my_bitmap.Planes[loop] )
  580.       FreeRaster( my_bitmap.Planes[loop], Width, Height );
  581.  
  582.  
  583.  
  584. 2.9  MAKE YOUR OWN CUSTOM POINTER
  585.  
  586. Each window can have its individual pointer. When the window
  587. becomes active the pointer can change image. This makes it
  588. easier for the user to see which window is active, and can
  589. also give the user a hint about what the computer is doing.
  590. For example, a wordprocessor can have a pointer that looks
  591. similar to a pencil, and when the computer is busy, the pointer
  592. change to a little Zzz symbol.
  593.  
  594. If your window is going to use a "custom" pointer you need to:
  595.   1. Allocate and initialize a Sprite data structure.
  596.   2. Use the function SetPointer() to change the window's
  597.      pointer.
  598.  
  599. When you are going to make a new image for your pointer, you
  600. first need to sketch how it should look like. The pointer is
  601. actually a Sprite (See chapter 10 SPRITES for more information
  602. about Sprites), and can therefore be up to 16 pixels wide, and
  603. be as tall as you want. You may use 3 colours, and transparent.
  604. (Since the pointer is a Sprite (no. 0) it can move between
  605. different screens with different resolutions, without destroying
  606. the display.)
  607.  
  608. A nice "arrow" pointer (16 pixels wide, 16 lines high) may look
  609. something like this:
  610.  
  611. 0000000200000000      0: Transparent
  612. 0000002200000000      1: Red
  613. 0000023200000000      2: Black
  614. 0000231200000000      3: White
  615. 0002311200000000
  616. 0023111222222200
  617. 0231111133333320
  618. 2311111111111132
  619. 0211111111111112
  620. 0021111222221112
  621. 0002111200023112
  622. 0000211200023112
  623. 0000021200023112
  624. 0000002200023112
  625. 0000000200023112
  626. 0000000000022222
  627.  
  628. You now need to translate this into Sprite Data. Each line of
  629. the pointer will be translated into two words of data. The
  630. first word represents the first Bitplane, and the second word
  631. the second Bitplane. The idea is that if you want colour 0 both
  632. Bitplane zero and one should be 0, if you want colour 1 Bitplane
  633. zero should be 1 and Bitplane one 0 and so on:
  634.  
  635. Colour  Bitplane One   Bitplane Zero           Since
  636. ------------------------------------------------------------
  637.   0           0              0         Binary 00 = Decimal 0
  638.   1           0              1            "   01 =    "    1
  639.   2           1              0            "   10 =    "    2
  640.   3           1              1            "   11 =    "    3
  641.  
  642. The data for the pointer would then look like this:
  643.  
  644.    Bitplane ZERO          Bitplane ONE
  645.  
  646. 0000 0000 0000 0000    0000 0001 0000 0000
  647. 0000 0000 0000 0000    0000 0011 0000 0000
  648. 0000 0010 0000 0000    0000 0111 0000 0000
  649. 0000 0110 0000 0000    0000 1101 0000 0000
  650. 0000 1110 0000 0000    0001 1001 0000 0000
  651. 0001 1110 0000 0000    0011 0001 1111 1100
  652. 0011 1111 1111 1100    0111 0000 1111 1110
  653. 0111 1111 1111 1110    1100 0000 0000 0011
  654. 0011 1111 1111 1110    0100 0000 0000 0001
  655. 0001 1110 0000 1110    0010 0001 1111 0001
  656. 0000 1110 0000 1110    0001 0001 0001 1001
  657. 0000 0110 0000 1110    0000 1001 0001 1001
  658. 0000 0010 0000 1110    0000 0101 0001 1001
  659. 0000 0000 0000 1110    0000 0011 0001 1001
  660. 0000 0000 0000 1110    0000 0001 0001 1001
  661. 0000 0000 0000 0000    0000 0000 0001 1111
  662.  
  663. The last step is to translate the binary numbers to base
  664. hexadecimal. Group the binary number in four and translate it
  665. to Hexadecimal:
  666.  
  667. 0000 =  0
  668. 0001 =  1
  669. 0010 =  2
  670. 0011 =  3
  671. 0100 =  4
  672. 0101 =  5
  673. 0110 =  6
  674. 0111 =  7
  675. 1000 =  8
  676. 1001 =  9
  677. 1010 =  A
  678. 1011 =  B
  679. 1100 =  C
  680. 1101 =  D
  681. 1110 =  E
  682. 1111 =  F
  683.  
  684. The result will look like this:
  685.  
  686.   ZERO:    ONE:
  687.   ------------
  688.   0000    0100
  689.   0000    0300
  690.   0200    0700
  691.   0600    0d00
  692.   0E00    1900
  693.   1E00    31FC
  694.   3FFC    60FE
  695.   7FFE    c003
  696.   3FFE    4001
  697.   1E0E    21F1
  698.   0E0E    1119
  699.   060E    0919
  700.   020E    0519
  701.   000E    0319
  702.   000E    0119
  703.   0000    001F
  704.  
  705. Since the Amiga need to store the position of the pointer, the
  706. size etc, you should also declare two empty words at the top,
  707. and to empty words at the bottom of the Sprite data. These
  708. words will be initialized and maintained by Intuition, so you
  709. do not need to bother about them.
  710.  
  711. A declaration and initialization of a nice arrow as Sprite data
  712. for a pointer would therefore be: (A hexadecimal number as 3FFE
  713. will written in C be 0x3FFE.)
  714.  
  715. UWORD chip my_sprite_data[36]=
  716. {
  717.  0x0000, 0x0000, /* Used by Intuition only. */
  718.  
  719.  0x0000, 0x0100,
  720.  0x0000, 0x0300,
  721.  0x0200, 0x0700,
  722.  0x0600, 0x0D00,
  723.  0x0E00, 0x1900,
  724.  0x1E00, 0x31FC,
  725.  0x3FFC, 0x60FE,
  726.  0x7FFE, 0xC003,
  727.  0x3FFE, 0x4001,
  728.  0x1E0E, 0x21F1,
  729.  0x0E0E, 0x1119,
  730.  0x060E, 0x0919,
  731.  0x020E, 0x0519,
  732.  0x000E, 0x0319,
  733.  0x000E, 0x0119,
  734.  0x0000, 0x001F,
  735.  
  736.  0x0000, 0x0000  /* Used by Intuition only. */
  737. };
  738.  
  739. It is actually not so complicated once you got used to it, but
  740. to make the life a bit easier I have written some utilities
  741. which will help you with translating graphics to sprite data.
  742. See the TOOL drawer for more information.
  743.  
  744.  
  745. The last step is to call the function SetPointer() which would
  746. look like this:
  747.  
  748. SetPointer( my_window, my_sprite_data, 16, 16, 0, -7);
  749.  
  750.   my_window:      Pointer to the window.
  751.   my_sprite_data: Pointer to the Sprite Data.
  752.   16:             Height.
  753.   16:             Width. (Must be 16 or less!)
  754.   0:              XOffset, left side. (Position of the Hot Spot)
  755.   -7:             YOffset, 7 lines down.         -"-
  756.  
  757. The "Hot Spot" is the pixel which should be the sensitive spot
  758. on the pointer. On the default pointer it is on the top left
  759. side, but on our custom pointer it should be on the left side
  760. (0), half way down (-7).
  761.  
  762. To restore the default pointer you simply call the function
  763. ClearPointer():
  764.  
  765. ClearPointer( my_window );
  766.  
  767.  
  768. Since you are going to use graphics data it is important that
  769. the data is placed in the Chip Memory. Chip Memory is the first
  770. 512 KB of RAM, and the graphics routines in the Amiga demands
  771. that Sprite Data, as well as other graphics data, is placed
  772. there. (The reason why is that the CPU on the Amiga can reach
  773. the first 9MB of RAM, while the Blitter (a graphics co-processor)
  774. only can reach the first 512 KB.
  775.  
  776. There will soon be a new Chip set for the Amiga 500 and 2000
  777. which enables the Blitter etc to reach the first 1 MB, but up
  778. to now the data MUST be placed somewhere in the memory between
  779. $00000 to $7FFFF.)
  780.  
  781. If you are using Lattice C Compiler V5.0 or higher it is very
  782. simple. You only need to place the little word "chip" in front
  783. of the data. Eg:
  784.   UWORD chip graphics_data[]={ ... };
  785.  
  786. On the Lattice C Compiler V4.0 you can compile the source with
  787. the added command: "-acdb" which will load everything into the
  788. Chip Memory. Eg:
  789.   lc -acdb -Lm my_program.c
  790.  
  791.   This will do both the lc1 and lc2 compilation, and it will
  792.   also link the code together with the standard math library. 
  793.   Everything is loaded into Chip Memory.
  794.  
  795. If you do not have one of these C compilers you will probably
  796. find out how to do it in your manual. REMEMBER! If you do not
  797. tell the compiler to always put the graphics in the Chip Memory
  798. you can end up with horrible bugs. It may sometimes work,
  799. especially if you have an unexpanded Amiga, but it will
  800. probably crash on an expanded Amiga.
  801.  
  802.  
  803.  
  804. 2.10  FUNCTIONS
  805.  
  806. Here are some functions that are often used together with
  807. windows:
  808.  
  809. OpenWindow()
  810.  
  811.   This function will open a window with the characteristics
  812.   defined in the NewWindow structure. It returns a pointer
  813.   to a Window structure.
  814.   
  815.   If you are going to use the Workbench screen, and it has
  816.   been closed, it will automatically reopen. If you on the
  817.   other hand is going to connect the window to a Custom screen,
  818.   you need to open it yourself before calling the OpenWindow()
  819.   function.
  820.   
  821.   Synopsis:      my_window = OpenWindow( my_new_window );
  822.  
  823.   my_window:     (struct Window *) Pointer to a Window structure
  824.                  or NULL if the window could not be opened.
  825.  
  826.   my_new_window: (struct NewWindow *) Pointer to a NewWindow
  827.                  structure which has been initialized with
  828.                  your requirements.
  829.  
  830.  
  831. CloseWindow()
  832.  
  833.   This function will close a window you have previously opened.
  834.   Remember that you need to close all windows connected to a
  835.   screen before you may close the screen, and all opened
  836.   windows must have been closed before your program quits.
  837.  
  838.   Synopsis:  CloseWindow( my_window );
  839.  
  840.   my_window: (struct Window *) Pointer to a Window structure
  841.              which has previously been initialized by an
  842.              OpenWindow() call.
  843.  
  844.  
  845. MoveWindow()
  846.  
  847.   This function will move a window. It has the same effect as
  848.   if the user would have moved the window by using the Drag
  849.   Gadget.
  850.  
  851.   Synopsis:  MoveWindow( my_window, delta_x, delta_y );
  852.  
  853.   my_window: (struct Window *) Pointer to a Window structure
  854.              which has previously been initialized by an
  855.              OpenWindow() call.
  856.  
  857.   delta_x:   (long) Deltamovement horizontally.
  858.  
  859.   delta_y:   (long) Deltamovement vertically.
  860.  
  861.  
  862. SizeWindow()
  863.  
  864.   This function will change the size of the window as desired.
  865.   It has the same effect as if the user would have resized the
  866.   window by using the Size Gadget.
  867.  
  868.   Synopsis:  SizeWindow( my_window, delta_x, delta_y );
  869.  
  870.   my_window: (struct Window *) Pointer to a Window structure
  871.              which has previously been initialized by an
  872.              OpenWindow() call.
  873.  
  874.   delta_x:   (long) Number of pixels the horizontally size of
  875.              the window will change.
  876.  
  877.   delta_y:   (long) Number of pixels the vertically size of the
  878.              window will change.
  879.  
  880.  
  881. WindowToFront()
  882.  
  883.   This function will put the window in front of all other
  884.   windows.
  885.  
  886.   Synopsis:  WindowToFront( my_window );
  887.  
  888.   my_window: (struct Window *) Pointer to a Window structure
  889.              which has previously been initialized by an
  890.              OpenWindow() call.
  891.  
  892.  
  893. WindowToBack()
  894.  
  895.   This function will push the window behind all other windows.
  896.  
  897.   Synopsis:  WindowToBack( my_window );
  898.  
  899.   my_window: (struct Window *) Pointer to a Window structure
  900.              which has previously been initialized by an
  901.              OpenWindow() call.
  902.  
  903.  
  904. SetWindowTitles()
  905.  
  906.   This function allows you to change the window title after the
  907.   window has been opened.
  908.   
  909.   Synopsis:  SetWindowTitles( my_window, window_t, screen_t );
  910.   
  911.   my_window: (struct Window *) Pointer to a Window structure
  912.              which has previously been initialized by an
  913.              OpenWindow() call.
  914.  
  915.   window_t:  (char *) Pointer to a NULL-terminated string which
  916.              will become the window's title, or
  917.                 0 : clear title bar, or
  918.                -1 : keep the old title.
  919.  
  920.   screen_t:  (char *) Pointer to a NULL-terminated string which
  921.              will become the window's screen title, or
  922.                 0 : clear title bar, or
  923.                -1 : keep the old title.
  924.  
  925.  
  926. WindowLimits()
  927.  
  928.   This function will change the maximum/minimum size limits of
  929.   the window. Any values which are set to 0 will remain
  930.   unchanged.
  931.  
  932.   Synopsis:  WindowLimits( my_window, min_w, min_h, max_w, max_h );
  933.  
  934.   my_window: (struct Window *) Pointer to a Window structure
  935.              which has previously been initialized by an
  936.              OpenWindow() call.
  937.  
  938.   min_w:     (long) Minimum width of the window.
  939.  
  940.   min_h:     (long) Minimum height of the window.
  941.  
  942.   max_w:     (long) Maximum width of the window.
  943.  
  944.   max_h:     (long) Maximum height of the window.
  945.  
  946.  
  947. SetPointer()
  948.  
  949.   This function allows you to change the window's pointer.
  950.   
  951.   Synopsis:  SetPointer( my_window, data, height, width, x, y );
  952.  
  953.   my_window: (struct Window *) Pointer to a Window structure
  954.              which has previously been initialized by an
  955.              OpenWindow() call.
  956.  
  957.   data:      (short *) Pointer to the Sprite data.
  958.  
  959.   width:     (long) The width of the pointer. Less or equal
  960.              to 16.
  961.  
  962.   height:    (long) The height of the pointer. Can be any
  963.              height.
  964.  
  965.   x:        (long) The pointer's "Hot Spot" x position.
  966.  
  967.   y:        (long) The pointer's "Hot Spot" y position.
  968.  
  969.  
  970. ClearPointer()
  971.  
  972.   This will remove the "custom" pointer, and replace it with
  973.   Intuition's default pointer.
  974.   
  975.   Synopsis:  ClearPointer( my_window );
  976.  
  977.   my_window: (struct Window *) Pointer to a Window structure
  978.              which has previously been initialized by an
  979.              OpenWindow() call.
  980.  
  981.  
  982. ReportMouse()
  983.  
  984.   You can call this function if you want the window to start/
  985.   stop reporting the mouse position. (See chapter 8 IDCMP for
  986.   more information about REPORTMOUSE.)
  987.   
  988.   Synopsis:  ReportMouse( my_window, boolean );
  989.  
  990.   my_window: (struct Window *) Pointer to a Window structure
  991.              which has previously been initialized by an
  992.              OpenWindow() call.
  993.  
  994.   boolean:   (long) Set to TRUE if you want the window to start
  995.              reporting mouse position, else set to FALSE, and
  996.              the window will stop reporting.
  997.  
  998.  
  999. BeginRefresh()
  1000.  
  1001.   This function will speed up your redrawing of the window. You
  1002.   should call this function before you start to refresh the
  1003.   window, and only the parts that needs to be redrawn are
  1004.   redrawn.
  1005.  
  1006.   Synopsis:  BeginRefresh( my_window );
  1007.  
  1008.   my_window: (struct Window *) Pointer to a Window structure
  1009.              which has previously been initialized by an
  1010.              OpenWindow() call.
  1011.  
  1012.  
  1013. EndRefresh()
  1014.  
  1015.   This function will tell Intuition that you have finished with
  1016.   your redrawings. IMPORTANT! If you receive a REFRESHWINDOW
  1017.   message, you must call the functions BeginRefresh() and
  1018.   EndRefresh(), even if you do not want to redraw anything.
  1019.   
  1020.   Synopsis:  EndRefresh( my_window );
  1021.  
  1022.   my_window: (struct Window *) Pointer to a Window structure
  1023.              which has previously been initialized by an
  1024.              OpenWindow() call.
  1025.  
  1026.  
  1027.  
  1028. 2.11  EXAMPLES
  1029.  
  1030. We have now looked at different types of windows, how to
  1031. connect System Gadgets, the steps to customize your pointer
  1032. and much more. It is now again time to look at some examples:
  1033.  
  1034. Example1
  1035.   This program will open a normal window which is connected to
  1036.   the Workbench Screen. It will display it for 30 seconds, and
  1037.   then close it.
  1038.  
  1039. Example2
  1040.   This program will open a high resolution 16 colour Custom
  1041.   Screen and a normal window which is connected to it. It will
  1042.   display it for 30 seconds, and then close the Custom Screen
  1043.   and the window.
  1044.  
  1045. Example3
  1046.   This program will open a normal window which is connected to
  1047.   the Workbench Screen. The window will use all System Gadgets,
  1048.   and will automatically Activate the window. It will display
  1049.   it for 30 seconds, and then close it. (Remember that the
  1050.   Close Gadget does NOT close the window by itself, it will
  1051.   only inform you that the user wants to close it. But in
  1052.   this example we will not listen to what the user wants.)
  1053.  
  1054. Example4
  1055.   This program will open two normal windows which are connected
  1056.   to the Workbench Screen. The windows will use all System
  1057.   Gadgets. It will display them for 30 seconds, and then close
  1058.   them.
  1059.  
  1060. Example5
  1061.   This program will open a Borderless window which is connected
  1062.   to the Workbench Screen. It will display it for 30 seconds,
  1063.   and then quit.
  1064.  
  1065. Example6
  1066.   Same as Example5 except that the window will also use all
  1067.   System Gadgets.
  1068.  
  1069. Example7
  1070.   This program will open three windows, two are normal and the
  1071.   third is a Backdrop window. The windows will use all System
  1072.   Gadgets, except the Backdrop window, which only can use the
  1073.   close-window gadget. After 30 seconds the program quits. (Try
  1074.   to push either window 1 or 2 behind the Backdrop window.)
  1075.  
  1076. Example8
  1077.   This program will open a SuperBitMap window which is
  1078.   connected to the Workbench Screen. Since it is a SuperBitMap
  1079.   we also make the window into a Gimmezerozero window. The
  1080.   window will use all System Gadgets, and some boxes will be
  1081.   drawn. It will display the window for 30 seconds, and then
  1082.   close it. (Shrink the window, and then enlarge it again, and
  1083.   you will noticed that the lines are still there!)
  1084.  
  1085. Example9
  1086.   This program will open a normal window with all system
  1087.   gadgets connected to it. If you activate the window, the
  1088.   pointer will change shapes into a "nice" arrow.
  1089.  
  1090. Example10
  1091.   This program will open a two normal windows with all system
  1092.   gadgets connected to them. If the first window is Activated,
  1093.   the pointer will change shapes into a Zzz symbol, if the
  1094.   second window is activated, the pointer will look like a
  1095.   pistol.